home *** CD-ROM | disk | FTP | other *** search
/ Aminet 1 (Walnut Creek) / Aminet - June 1993 [Walnut Creek].iso / usenet / sources / volume90 / unix / cpp / part01 / org / cpp.rno < prev    next >
Text File  |  1990-01-18  |  8KB  |  292 lines
  1. .lm 8.rm 72.nhy
  2.  
  3. .no autosubtitle .style headers 3,0,0
  4. .pg.uc.ps 58,80.lm 8.rm 72
  5. .hd
  6. .hd mixed
  7. .head mixed
  8.  
  9. .st ########cpp#####C Pre-Processor
  10. .pg
  11. .hl 1 ^&C Pre-Processor\&
  12. .s 2
  13. .c ;*******
  14. .c ;* cpp *
  15. .c ;*******
  16. .s 2
  17. .lm +8
  18. .s.i -8;NAME:    cpp -- C Pre-Processor
  19. .s.f
  20. .i -8;SYNOPSIS:
  21. .s.nf
  22. cpp [-options] [infile [outfile]]
  23. .s.f
  24. .i -8;DESCRIPTION:
  25. .s
  26. CPP reads a C source file, expands macros and include
  27. files, and writes an input file for the C compiler.
  28. If no file arguments are given, CPP reads from stdin
  29. and writes to stdout.  If one file argument is given,
  30. it will define the input file, while two file arguments
  31. define both input and output files.  The file name "-"
  32. is a synonym for stdin or stdout as appropriate.
  33. .s
  34. The following options are supported.  Options may
  35. be given in either case.
  36. .lm +16
  37. .p -16
  38. -C        If set, source-file comments are written
  39. to the output file.  This allows the output of CPP to be
  40. used as the input to a program, such as lint, that expects
  41. commands embedded in specially-formatted comments.
  42. .p -16
  43. -Dname=value    Define the name as if the programmer wrote
  44. .s
  45. .nf
  46.     _#define name value
  47. .s
  48. .fill
  49. at the start of the first file.  If "=value" is not
  50. given, a value of "1" will be used.
  51. .s
  52. On non-unix systems, all alphabetic text will be forced
  53. to upper-case.
  54. .p -16
  55. -E        Always return "success" to the operating
  56. system, even if errors were detected.  Note that some fatal
  57. errors, such as a missing _#include file, will terminate
  58. CPP, returning "failure" even if the -E option is given.
  59. .p -16
  60. -Idirectory    Add this directory to the list of
  61. directories searched for _#include "..." and _#include <...>
  62. commands.  Note that there is no space between the
  63. "-I" and the directory string.  More than one -I command
  64. is permitted.  On non-Unix systems "directory" is forced
  65. to upper-case.
  66. .p -16
  67. -N        CPP normally predefines some symbols defining
  68. the target computer and operating system.  If -N is specified,
  69. no symbols will be predefined.  If -N -N is specified, the
  70. "always present" symbols, ____LINE____, ____FILE____, and ____DATE____
  71. are not defined.
  72. .p -16
  73. -Stext        CPP normally assumes that the size of
  74. the target computer's basic variable types is the same as the size
  75. of these types of the host computer.  (This can be overridden
  76. when CPP is compiled, however.)  The -S option allows dynamic
  77. respecification of these values.  "text" is a string of
  78. numbers, separated by commas, that specifies correct sizes.
  79. The sizes must be specified in the exact order:
  80. .s
  81. .nf
  82.     char short int long float double
  83. .s
  84. .fill
  85. If you specify the option as "-S*text", pointers to these
  86. types will be specified.  -S* takes one additional argument
  87. for pointer to function (e.g. int (*)())
  88. .s
  89. For example, to specify sizes appropriate for a PDP-11,
  90. you would write:
  91. .s
  92. .nf
  93.        c s i l f d func
  94.      -S1,2,2,2,4,8,
  95.     -S*2,2,2,2,2,2,2
  96. .s
  97. .fill
  98. Note that all values must be specified.
  99. .p -16
  100. -Uname        Undefine the name as if
  101. .s
  102. .nf
  103.     _#undef name
  104. .s
  105. .fill
  106. were given.  On non-Unix systems, "name" will be forced to
  107. upper-case.
  108. .p -16
  109. -Xnumber    Enable debugging code.  If no value is
  110. given, a value of 1 will be used.  (For maintenence of
  111. CPP only.)
  112. .s.lm -16
  113. .s
  114. .i -8;PRE-DEFINED VARIABLES:
  115. .s
  116. When CPP begins processing, the following variables will
  117. have been defined (unless the -N option is specified):
  118. .s
  119. Target computer (as appropriate):
  120. .s
  121. .nf
  122.     pdp11, vax, M68000 m68000 m68k
  123. .fill
  124. .s
  125. Target operating system (as appropriate):
  126. .s
  127. .nf
  128.     rsx, rt11, vms, unix
  129. .fill
  130. .s
  131. Target compiler (as appropriate):
  132. .s
  133. .nf
  134.     decus, vax11c
  135. .fill
  136. .s
  137. The implementor may add definitions to this list.
  138. The default definitions match the definition of the
  139. host computer, operating system, and C compiler.
  140. .s
  141. The following are always available unless undefined (or
  142. -N was specified twice):
  143. .lm +16
  144. .p -12
  145. ____FILE____    The input (or _#include) file being compiled
  146. (as a quoted string).
  147. .p -12
  148. ____LINE____    The line number being compiled.
  149. .p -12
  150. ____DATE____    The date and time of compilation as
  151. a Unix ctime quoted string (the trailing newline is removed).
  152. Thus,
  153. .s
  154. .nf
  155.     printf("Bug at line _%s,", ____LINE____);
  156.     printf(" source file _%s", ____FILE____);
  157.     printf(" compiled on _%s", ____DATE____);
  158. .fill
  159. .s.lm -16
  160. .s
  161. .i -8;DRAFT PROPOSED ANSI STANDARD CONSIDERATIONS:
  162. .s
  163. The current version of the Draft Proposed Standard
  164. explicitly states that "readers are requested not to specify
  165. or claim conformance to this draft."  Readers and users
  166. of Decus CPP should not assume that Decus CPP conforms
  167. to the standard, or that it will conform to the actual
  168. C Language Standard.
  169. .s
  170. When CPP is itself compiled, many features of the Draft
  171. Proposed Standard that are incompatible with existing
  172. preprocessors may be disabled.  See the comments in CPP's
  173. source for details.
  174. .s
  175. The latest version of the Draft Proposed Standard (as reflected
  176. in Decus CPP) is dated November 12, 1984.
  177. .s
  178. Comments are removed from the input text.  The comment
  179. is replaced by a single space character.  The -C option
  180. preserves comments, writing them to the output file.
  181. .s
  182. The '$' character is considered to be a letter.  This is
  183. a permitted extension.
  184. .s
  185. The following new features of C are processed by CPP:
  186. .s.comment Note: significant spaces, not tabs, .br quotes #if, #elif
  187. .br;####_#elif expression    (_#else _#if)
  188. .br;####'_\xNNN'             (Hexadecimal constant)
  189. .br;####'_\a'                (Ascii BELL)
  190. .br;####'_\v'                (Ascii Vertical Tab)
  191. .br;####_#if defined NAME    1 if defined, 0 if not
  192. .br;####_#if defined (NAME)  1 if defined, 0 if not
  193. .br;####_#if sizeof (basic type)
  194. .br;####unary +
  195. .br;####123U, 123LU          Unsigned ints and longs.
  196. .br;####12.3L                Long double numbers
  197. .br;####token_#token         Token concatenation
  198. .br;####_#include token      Expands to filename
  199. .s
  200. The Draft Proposed Standard has extended C, adding a constant
  201. string concatenation operator, where
  202. .s
  203. .nf
  204.     "foo" "bar"
  205. .s
  206. .fill
  207. is regarded as the single string "foobar".  (This does not
  208. affect CPP's processing but does permit a limited form of
  209. macro argument substitution into strings as will be discussed.)
  210. .s
  211. The Standard Committee plans to add token concatenation
  212. to _#define command lines.  One suggested implementation
  213. is as follows:  the sequence "Token1_#Token2" is treated
  214. as if the programmer wrote "Token1Token2".  This could
  215. be used as follows:
  216. .s
  217. .nf
  218.     _#line 123
  219.     _#define ATLINE foo_#____LINE____
  220. .s
  221. .fill
  222. ATLINE would be defined as foo123.
  223. .s
  224. Note that "Token2" must either have the format of an
  225. identifier or be a string of digits.  Thus, the string
  226. .s
  227. .nf
  228.     _#define ATLINE foo_#1x3
  229. .s
  230. .fill
  231. generates two tokens: "foo1" and "x3".
  232. .s
  233. If the tokens T1 and T2 are concatenated into T3,
  234. this implementation operates as follows:
  235. .s
  236. .nf
  237.   1. Expand T1 if it is a macro.
  238.   2. Expand T2 if it is a macro.
  239.   3. Join the tokens, forming T3.
  240.   4. Expand T3 if it is a macro.
  241. .s
  242. .fill
  243. A macro formal parameter will be substituted into a string
  244. or character constant if it is the only component of that
  245. constant:
  246. .s
  247. .nf
  248.     _#define VECSIZE 123
  249.     _#define vprint(name, size) _\
  250.       printf("name" "[" "size" "] = {_\n")
  251.       ... vprint(vector, VECSIZE);
  252. .s
  253. .fill
  254. expands (effectively) to
  255. .s
  256. .nf
  257.       vprint("vector[123] = {_\n");
  258. .s
  259. .fill
  260. Note that this will be useful if your C compiler supports
  261. the new string concatenation operation noted above.
  262. As implemented here, if you write
  263. .s
  264. .nf
  265.     _#define string(arg) "arg"
  266.       ... string("foo") ...
  267. .s
  268. .fill
  269. This implementation generates "foo", rather than the strictly
  270. correct ""foo"" (which will probably generate an error message).
  271. This is, strictly speaking, an error in CPP and may be removed
  272. from future releases.
  273. .s
  274. .i -8;ERROR MESSAGES:
  275. .s
  276. Many.  CPP prints warning or error messages if you try to
  277. use multiple-byte character constants (non-transportable)
  278. if you _#undef a symbol that was not defined, or if your
  279. program has potentially nested comments.
  280. .s
  281. .i -8;AUTHOR:
  282. .s
  283. Martin Minow
  284. .s
  285. .i -8;BUGS:
  286. .s
  287. The _#if expression processor uses signed integers only.
  288. I.e, _#if 0xFFFFu < 0 may be TRUE.
  289. .s
  290. .lm 8.rm 72.nhy
  291.  
  292.